home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / GSOS / TN.GSOS.013 < prev   
Encoding:
Text File  |  1991-11-15  |  7.8 KB  |  173 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. GS/OS
  8. #13:         GS/OS Reference Update
  9.  
  10. Revised by:  Matt Deatherage                                    December 1991
  11. Written by:  Matt Deatherage                                    November 1990
  12.  
  13. This Technical Note corrects and updates the Addison-Wesley Apple IIgs GS/OS 
  14. Reference.  Previous versions from APDA labeled Volume 1 or 2 are 
  15. obsolete,and should no longer be used.
  16.  
  17. Changes since March 1991:  Added clarifications about the option_list
  18.                            structure.  Corrected more diagrams.  Clarified 
  19.                            system level description to be more precise.
  20. _____________________________________________________________________________
  21.  
  22.  
  23. Chapter 4, "Accessing GS/OS Files"
  24.  
  25. Page 72:  The System File Level:  How to Protect an Open File From the
  26. Application
  27.  
  28. The class 1 SetLevel and GetLevel calls have a special option that allows you
  29. to open a file at an "internal" file level, so that it cannot be closed by an
  30. application making a Close call with reference number zero at any application
  31. level.
  32.  
  33. GetLevel and SetLevel actually accept two parameters, not just the one
  34. parameter (level) documented in Chapter 7.  The second parameter, level_mode,
  35. is a Word that controls the internal range of the file level.
  36.  
  37. Only two values for level_mode are supported.  A value of $8000 is the same as
  38. if the parameter wasn't present at all--the level calls behave just as
  39. documented in GS/OS Reference.  A value of $0000 sets a special "system" or
  40. "internal" level--all files opened with an internal level are unaffected by
  41. any non-internal level.
  42.  
  43. The steps to open a file at an internal file level are:
  44.  
  45. 1.  Call GetLevel with pCount=2, level_mode=$0000.  Save the returned level.
  46. 2.  Call SetLevel with pCount=2, level = $0080 and level_mode = $0000.
  47. 3.  Open a file or files with a class 0 or 1 Open call, or with
  48.     OpenResourceFile (OpenResourceFile on System Software 5.0.4 and earlier
  49.     does not try to protect your resource files from being accidentally 
  50.     closed by a Close(0)).
  51. 4.  Call SetLevel with pCount=2, level_mode=$0000, and level = saved level.
  52.  
  53. You can use two parameters in all your level calls and set the second
  54. level_mode parameter to $8000 instead of omitting it if it will make writing
  55. your program easier.
  56.  
  57. To close your protected file, simply do a Close with the reference number.
  58. There is no need to fiddle with the file level when closing by reference
  59. number.
  60.  
  61. NDAs should close all their files at or before DeskShutDown time.
  62.  
  63. Chapter 6, "Working with System Information"
  64.  
  65. Page 92:  Using the optionList parameter
  66.  
  67. The optionList parameter resembles a GS/OS output buffer in most 
  68. important respects--it starts with a word indicating the size of the 
  69. buffer, and each FST fills in the size of the actual data placed in the 
  70. buffer in the second word.   If the buffer is too small to hold the 
  71. data, the necessary size is placed in the second word and the FST 
  72. returns the "buffer too small" error ($004F).
  73.  
  74. Usually, GS/OS input buffers only have one length word, because if you 
  75. know how large the data is (and you do if you're the one passing it to 
  76. GS/OS), you don't need another word telling you the same thing.   
  77. However, if you're trying to copy something like an optionList, you can 
  78. wind up in a bit of a pickle.   Just because the buffer you've allocated 
  79. is big enough to hold file system-specific information, that doesn't 
  80. mean the information is necessarily present.
  81.  
  82. A good example of this problem is found in the System Software 6.0 
  83. ProDOS FST.  In 6.0 and later, the ProDOS FST will take HFS Finder 
  84. information (as returned by the AppleShare and HFS FSTs) in the 
  85. optionList and place that information in an extended file's extended key 
  86. block, so the file can be copied to and from ProDOS disks with no loss 
  87. of Macintosh-specific information (such as the longer file types and 
  88. creator types necessary to identify Macintosh files).  The FST returns 
  89. the same information (if present) in the output optionList.
  90.  
  91. However, previous versions of the ProDOS FST returned no information in 
  92. the optionList.  Suppose you archived a file and stored the optionList 
  93. with the file's information under 5.0, and attempt to restore the file 
  94. under 6.0 using a nice, large optionList buffer.  The FST can't know 
  95. whether the large buffer contains any information or not.
  96.  
  97. To remedy this problem, the second word of the optionList structure 
  98. (reqSize in the figure on page 92) is now defined on input as well as 
  99. output.  On input, the word must contain the actual size of the data in 
  100. the optionList; the first word continues to indicate the size of the 
  101. entire buffer.  If the buffer size and the actual data size are too 
  102. small to make sense, any affected FSTs will ignore the input, knowing 
  103. that it must be garbage.
  104.  
  105. Further details on how the ProDOS FST stores HFS Finder information can 
  106. be found in ProDOS 8 Technical Note #25, "Non-Standard Storage Types."
  107.  
  108. Chapter 7, "GS/OS Call Reference"
  109.  
  110. Pages 98-99:  ChangePath
  111.  
  112. On page 98, the ReferenceJstates that a subdirectory may not be moved into
  113. itself or into a directory the first subdirectory already contains.  For
  114. example, you may not change /v to /v/w or /v/w to /v/w/x.  Although this is
  115. correct, the System Software 5.0.x implementations of the ProDOS FST trash 
  116. your disk if you try this with ChangePath.  Do not try it on disks you want 
  117. tokeep.
  118.  
  119. On page 99, error $4E is described as "file not destroy-enabled."  No, 
  120. ChangePath doesn't destroy the file.  The error should read "file not 
  121. rename-enabled."
  122.  
  123. Page 120:  DInfo Characteristics Word
  124.  
  125. The diagram for the characteristics word in the DInfo parameters has 
  126. incorrect descriptions for bits 14 and 13.   The diagram says bit 14 is 
  127. set if the device is a linked device; in fact, bit 13 is set if the 
  128. device is a linked device.   Bit 14 is set if the device in question has 
  129. a generated driver; the bit is clear for loaded drivers.
  130.  
  131. Page 129:  The Character Device Status Word
  132.  
  133. The diagram on the top of page 129 says that if bit 5 is set, the device isin 
  134. no-wait mode.  This is incorrect.  To determine if a device is in 
  135. no-waitmode, make the GetWaitStatus subcall described on page 130.
  136.  
  137. Bit 5 of the character device status word is set if there are one or more 
  138. characters waiting to be read from the device.  This is an assistance for 
  139. developers, since generated character drivers don't support no-wait mode.
  140.  
  141. Page 132:  GetFormatOptions Flags Word
  142.  
  143. The diagram describing the flags word of GetFormatOptions is incorrect.   
  144. Bits 0 and 1 are actually the format type, while bits 2 and 3 are the 
  145. size multiplier.   In other words, the two labels are backwards.
  146.  
  147. Page 142:  Flush
  148.  
  149. The Flush call, under System Software 5.0.3 and later (GS/OS version 3.3) 
  150. accepts a maximum of two parameters.  If the second parameter is present, 
  151. itis the flushType.  The flushType Word specifies the type of flush to 
  152. beperformed. A flushType of $0000 is the standard flush, where all dirty 
  153. blocks arewritten to disk.  If flushType is $8000, however, only dirty data 
  154. blocks are writtento disk.  Dirty system blocks (directories, bitmaps, etc.) 
  155. are not flushed inthis fast flush.
  156.  
  157.  
  158. Appendix A, "GS/OS ProDOS 16 Calls"
  159.  
  160. Page 386:  GetDirEntry buffer description incorrect
  161.  
  162. On page 386, nameBuffer is described as a pointer to a buffer in which GS/OS 
  163. returns a Pascal string containing the name of the file or directory entry(in 
  164. GetDirEntry).  This is incorrect; all versions of GetDirEntry return GS/OS 
  165. (word-length) strings for the directory entry.
  166.  
  167.  
  168. Further Reference
  169. _____________________________________________________________________________
  170.   o  GS/OS Reference
  171.   o  Apple IIgs Technical Note #71, DA Tips and Techniques
  172.   o  ProDOS 8 Technical Note #25, Non-Standard Storage Types
  173.